/*
 * 版权所有 (C) 2015 知启蒙(ZHIQIM) 保留所有权利。[遇见知启蒙，邂逅框架梦]
 * 
 * https://zhiqim.org/project/zhiqim_framework/zhiqim_orm.htm
 *
 * Zhiqim Orm is licensed under Mulan PSL v2.
 * You can use this software according to the terms and conditions of the Mulan PSL v2.
 * You may obtain a copy of Mulan PSL v2 at:
 *          http://license.coscl.org.cn/MulanPSL2
 * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
 * EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
 * MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
 * See the Mulan PSL v2 for more details.
 */
package org.zhiqim.orm;

import java.sql.SQLException;
import java.util.List;

import org.zhiqim.kernel.MultiInstance;
import org.zhiqim.kernel.annotation.AnAlias;
import org.zhiqim.kernel.model.maps.MapSO;
import org.zhiqim.kernel.paging.PageResult;
import org.zhiqim.orm.dbo.Selector;

/**
 * 视图类与数据库表多表映射调用，支持(count,sum,item,list,page)<br><br>
 * count,       统计视图类对应的关联表数目<br>
 * sum,         总计视图类对应的关联表数目<br>
 * item,        查询视图类对应的关联表一条数据，根据主键，或根据条件排序取第一条<br>
 * list,        查询视图类对应的关联表列表，或根据条件排序<br>
 * pag,         分页查询视图类对应的关联表列表，指定分页页码和页数目<br>
 * 
 * @version v1.0.0 @author zouzhigang 2014-3-21 新建与整理
 * @version v1.2.0 @author zouzhigang 2016-6-27 修改原类名FRHEL为ZView，正式使用视图名称
 */
@AnAlias("ZView")
public interface ZView extends MultiInstance
{
    /*****************************************************/
    //count 查询数目
    /*****************************************************/
    
    /**
     * 查询数目，查全视图
     * 
     * @param cls           视图类
     * @return              返回数目
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public int count(Class<?> cls)throws ORMException, SQLException;
    
    /**
     * 查询数目，根据条件、可替换表查询
     * 
     * @param cls           视图类
     * @param selector      对象查询器
     * @return              返回数目
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public int count(Class<?> cls, Selector selector)throws ORMException, SQLException;

    /**
     * 分组查询数目，根据条件、可替换表和分组字段
     * 
     * @param cls           表类
     * @param selector
     * @return
     * @throws ORMException
     * @throws SQLException
     */
    public List<MapSO> countGroupBy(Class<?> cls, Selector selector) throws ORMException, SQLException;
    
    /*****************************************************/
    //sum 计算总和
    /*****************************************************/
    
    /**
     * 计算总和，全视图求和
     * 
     * @param cls           视图类
     * @param field         视图字段
     * @return              返回总和
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public long sum(Class<?> cls, String field) throws ORMException, SQLException;
    
    /**
     * 计算总和，根据条件视图中求和
     * 
     * @param cls           视图类
     * @param field         视图字段
     * @param selector      查询器
     * @return              返回总和(sum)
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public long sum(Class<?> cls, String field, Selector selector) throws ORMException, SQLException;
    
    /**
     * 计算多个总和，全视图中多个求和
     * 
     * @param cls           视图类
     * @param fieldArr      多个视图字段
     * @return              返回计算多个总和
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public long[] sum(Class<?> cls, String[] fieldArr) throws ORMException, SQLException;
    
    /**
     * 计算多个总和，根据条件视图中多个求和
     * 
     * @param cls           视图类
     * @param fieldArr      多个视图字段
     * @param selector      查询器
     * @return              返回计算多个总和
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public long[] sum(Class<?> cls, String[] fieldArr, Selector selector) throws ORMException, SQLException;
    
    /*****************************************************/
    //item 查询一条数据
    /*****************************************************/
    
    /**
     * 查询一个视图对象,全视图中取第一个
     * 
     * @param cls           视图类
     * @return              返回视图对象
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> T item(Class<T> cls) throws ORMException, SQLException;
    
    /**
     * 查询一个视图对象,可排序取第一个
     * 
     * @param cls           视图类
     * @param selector      查询器
     * @return              返回视图对象
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> T item(Class<T> cls, Selector selector) throws ORMException, SQLException;
    
    /*****************************************************/
    //list 查询列表
    /*****************************************************/
    
    /**
     * 查询列表，查全视图
     * 
     * @param cls           视图类
     * @return              视图对象列表
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> List<T> list(Class<T> cls) throws ORMException, SQLException;
    
    /**
     * 查询列表，根据查询器
     * 
     * @param cls           视图类
     * @param selector      查询器
     * @return              视图对象列表
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> List<T> list(Class<T> cls, Selector selector) throws ORMException, SQLException;
    
    /**
     * 查询表对象列表，查询指定的位置的数据
     * 
     * @param cls           表类
     * @param pageNo        页码
     * @param pageSize      页数
     * @return              返回表对象列表
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> List<T> list(Class<T> cls, int pageNo, int pageSize) throws ORMException, SQLException;
    
    /**
     * 查询表对象列表，并指定位置的,条件和排序条件
     * 
     * @param cls           表类
     * @param pageNo        页码
     * @param pageSize      页数
     * @param selector      对象查询器
     * @return              返回表对象列表
     * @throws ORMException 映射异常,如果传入的属性不在配置文件中则异常
     * @throws SQLException 数据库异常
     */
    public <T> List<T> list(Class<T> cls, int pageNo, int pageSize, Selector selector) throws ORMException, SQLException;
    
    /*****************************************************/
    //page 分页显示
    /*****************************************************/
    
    /**
     * 查询视图分页信息，查全视图
     * 
     * @param cls           视图类
     * @param pageNo        页码
     * @param pageSize      页数
     * @return              分页信息,包括总页数,页码,页数和查询的记录
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> PageResult<T> page(Class<T> cls, int pageNo, int pageSize) throws ORMException, SQLException;
    
    /**
     * 查询视图分页信息，查全视图
     * 
     * @param cls           视图类
     * @param pageNo        页码
     * @param pageSize      页数
     * @param total         指定总数，不作count计算
     * @return              分页信息,包括总页数,页码,页数和查询的记录
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> PageResult<T> page(Class<T> cls, int pageNo, int pageSize, int total) throws ORMException, SQLException;
    
    /**
     * 查询视图分页信息
     * 
     * @param cls           视图类
     * @param pageNo        页码
     * @param pageSize      页数
     * @param selector      查询器
     * @return              分页信息,包括总页数,页码,页数和查询的记录
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> PageResult<T> page(Class<T> cls, int pageNo, int pageSize, Selector selector) throws ORMException, SQLException;
    
    /**
     * 查询视图分页信息
     * 
     * @param cls           视图类
     * @param pageNo        页码
     * @param pageSize      页数
     * @param selector      查询器
     * @param total         指定总数，不作count计算
     * @return              分页信息,包括总页数,页码,页数和查询的记录
     * @throws ORMException 映射异常
     * @throws SQLException 数据库异常
     */
    public <T> PageResult<T> page(Class<T> cls, int pageNo, int pageSize, int total, Selector selector) throws ORMException, SQLException;
}
